<!DOCTYPE html>
<!--[if lt IE 7]>      <html class="lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]>         <html class="lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]>         <html class="lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html class=""> <!--<![endif]-->
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
     <meta property="qc:admins" content="63350727776371646636" />
  
  
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width,initial-scale=1.0,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no">
  <title> SwiftV课堂 - 中国最大的Swift视频学习站</title>
  <meta name="keywords" content="swift,swift 教程,swift视频,swift论坛,swiftv课堂,swift培训,swift开发,ios8 开发,ios9 编程" />
  <meta name="description" content="SwiftV课堂是国内氛围最好的swift学习、交流网站，提供上千套swift视频,swift教程免费观看，学Swift开发(iOS10 开发)就上SwiftV课堂。" />
  <link rel="shortcut icon" type="image/x-icon" href="http://static.vlms.cn/images/2014/08/hyjpep4o.png" media="screen" />
  
  <link href="http://static.vlms.cn/resources/bootstrap/css/bootstrap.css" rel="stylesheet" />
  <link rel="stylesheet" media="screen" href="http://static.vlms.cn/resources/bootstrap/css/bootstrap-extends.css" />
  
  <!-- 预览、自定义、默认css样式  -->
  	<link rel="stylesheet" media="screen" href="http://static.vlms.cn/resources/css/schoolweb.css" />
  
  <!-- 回到顶部样式  -->
  <link rel="stylesheet" media="screen" href="http://static.vlms.cn/resources/css/upDown.css" />
  
  <script src="http://static.vlms.cn/resources/js/jquery.min.js"></script>
  <script src="http://static.vlms.cn/resources/js/main.js"></script>
  
  <!-- 回到顶部样式  -->
  <script src="http://static.vlms.cn/resources/js/JQscrollTop.js"></script>
  <script src="http://static.vlms.cn/resources/js/updown.js"></script>
  
    <!--[if lt IE 8]>
      <link href="//static.vlms.cn/resources/wangxiaoyun/css/oldie.css" rel="stylesheet">
    <![endif]-->
    
    <!--[if lt IE 9]>
    <script src="//static.vlms.cn/resources/wangxiaoyun/libs/html5shiv.js"></script>
    <![endif]-->

	  <!--[if IE 8]>
	    <script src="//static.vlms.cn/resources/wangxiaoyun/libs/respond.min.js"></script>
	  <![endif]-->
  
</head>
<body id="bodyColor" class="">

<style>
.nav-list > li.active > a {
    background-color: #ffa275;  
    color: #ffffff;
}

.site-navbar .navbar-nav > li > a:hover {
    background-color: #ffa275;
    color: #ffffff;
}
</style>

<div class="navbar navbar-inverse site-navbar" id="site-navbar">
  <div class="container">
    <div class="container-gap">
      <div class="navbar-header">
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
          <a class="navbar-brand-logo" href="../index.html">
            <img src="http://static.vlms.cn/images/2015/07/ic4hqb7b.png" alt="SwiftV课堂" title="SwiftV课堂" height="55px;" />
          </a>
      </div>
      
      <div class="navbar-collapse collapse">
          <ul class="nav navbar-nav">
              <li><a href="../course/explore-sort=latest.html"  >全部课程</a></li>
              <li><a href="https://www.boxueio.com/skill/swift?v"  target="_blank"  >如何学Swift？</a></li>
              <li><a href="../page/qun.html"  >Q群公布</a></li>
              <li><a href="../page/lianxi.html"  >联系我们</a></li>
          </ul>
        
        <ul class="nav navbar-nav navbar-right">
          <li>
	        <span class="nav navbar-nav" style="margin-top:10px;width:170px;">
	          <input class="typehead form-control search_input" type="text" placeholder="搜索课程或用户" style="display:inline;background:#5c5f68; border: 0px solid #5c5f68;width:130px;" data-role="item-input">
		      <button class="btn btn-default xin-search-btn" type="submit" data-role="item-add" style="margin-left:-10px;margin-top:-3px;background-color:#5c5f68;border: 1px solid #5c5f68;color:#a1a4ac;"><i class="glyphicon glyphicon-search"></i></button>
	    	</span>            
          </li>  
            <li><a href="../login.html">登录</a></li>
               <li><a href="../register.html">注册</a></li>
        </ul>        

      </div><!--/.navbar-collapse -->
    </div>
  </div>
</div>


<script>
   $(document).ready(function(){
      $(".typehead").click(function(){
          $(this).css("background","white");
          $(".xin-search-btn").css({"background":"white","border":"1px solid #FFFFFF"});
      });
      
   	  $(".typehead").blur(function(){
          $(this).css("background","#5c5f68");
           $(".xin-search-btn").css({"background":"#5c5f68","border":"1px solid #5c5f68"});
      });
      
	  //搜索按钮
	  $(".xin-search-btn").click(function(){
	   	var key=$(".search_input").val();
	   	var url = "";
	   	if (getUrlParam('theme')) {
	   		var value = getUrlParam('theme');
	   		url="/search/course?keyword="+key+"&theme="+value;
	   	}else{
			url="/search/course?keyword="+key;
		}
		location.href=url;
	  });
	  
	  	//获取url中的参数
		function getUrlParam(name) {
			var reg = new RegExp("(^|&)" + name + "=([^&]*)(&|$)"); //构造一个含有目标参数的正则表达式对象
			var r = window.location.search.substr(1).match(reg);  	//匹配目标参数
			if (r != null) return unescape(r[2]); return null; 		//返回参数值
		}
	
   });
</script>


<div id="content-container" class="container">
        <div class="wxy-row-wrap container-gap" style="padding:15px 26px;">
  		<div class="row form-group">
  		
			    <div class="col-md-12">
			      <div class="page-header">
			        <h1>使用“Markdown方言”编写代码注释-Swift 3  <div class="pull-right" style="font-size:12px;padding:26px 20px; color:#7abaf5;">
			        <span>
		        		日期：2016-06-22 12:26:29
	        		</span>
	        		</div></h1>
			       
			      </div>
			      
			    </div>
	 
	  			<div class="col-md-12" style="padding-bottom:20px;">
			    <div class="control-label"> <label for="content">摘要：</label> </div>
			        <p style="padding-left:30px;padding-right:30px;"> 点评：做为伴随Swift 3发布的API设计指南中的要求，使用Swift Markdown为代码编写注释已经进一步从一个道义提升为了一种行为准则。一方面，Markdown对开发者来说，足够熟悉，学习难度并不高；另一方面，Xcode可以在Playground和代码提示中，对Markdown注释进行漂亮的渲染，让代码在开发者之间交流起来更加容易。
</br>原文链接：<a href="https://boxueio.com/series/swift-up-and-running/episode/84" target="_blank"><span style="color:#337FE5;"><u>https://boxueio.com/series/swift-up-and-running/episode/84</u></span></a><span style="line-height:1.5;"></span>作者：泊学</p>
			     </div>
			     
			    <div class="col-md-12" style="padding-bottom:20px;">
			    <div class="control-label"> <label for="content">内容：</label> </div>
			        <p style="padding-left:30px;padding-right:30px;"> <p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	做为伴随Swift 3发布的API设计指南中的要求，<span style="font-weight:700;">使用Swift Markdown为代码编写注释</span>已经进一步从一个道义提升为了一种行为准则。一方面，Markdown对开发者来说，足够熟悉，学习难度并不高；另一方面，Xcode可以在Playground和代码提示中，对Markdown注释进行漂亮的渲染，让代码在开发者之间交流起来更加容易。既然如此，我们就通过这段视频，带着大家快速过一遍Swift中的Markdown注释机制，了解它们在Xcode哪些地方会被渲染出来。
	</p>
<h2 id="toc_1" style="font-family:" font-weight:normal;color:#555555;font-size:24px;background-color:#ffffff;"="">
	从一个包含playground文件的Single View Application开始
		</h2>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	为了演示Markdown注释在Xcode中的各种效果，我们创建一个Single View Application，并向其中添加了一个MyPlayground文件以及一个包含struct IntArray类型的源代码文件。因为，在Xcode在Playground和项目源代码中，使用了两种不同的Markdown注释格式，我们要分别了解它们。
			</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	为了能快速切换Markdown注释在Playground中的渲染效果，我们可以按Command + ,打开属性对话框，选择“Key Bindings”
		</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
		<div class="col-md-12">
			<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-1@2x.jpg" alt="Key bindings" style="width:750px;" /> 
		</div>
			</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	在“Filter”中，输入Show rendered，Xcode会为我们自动过滤出筛选的菜单项目，“Show rendered Markup”用于在Playground里，切换Markdown注释的渲染。双击右侧的空白，为它设定一个快捷键，例如：option + M：
				</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
				<div class="col-md-12">
					<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-2@2x.jpg" alt="Show rendered markdown" style="width:750px;" /> 
				</div>
					</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	这样，我们就能通过设置的快捷键在Playground中快速切换Markdown的渲染效果了。接下来，我们就来看各种常用的Markdown用法。
						</p>
						<hr />
						<h3 id="toc_2" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	Playground
							</h3>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
							<li style="font-size:15px;">
								包含Markdown的单行注释用//:表示：
							</li>
								</ul>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">//: # Heading 1</span> </pre>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
								<li style="font-size:15px;">
									包含Markdown的多行注释用下面的代码表示：
								</li>
							</ul>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/*:
  * item1
  * item2
  * item3
 */</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	按Option + M，Playground就会自动为我们渲染注释了：
								</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
								<div class="col-md-12">
									<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-3@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
								</div>
									</div>
									<hr />
									<h3 id="toc_3" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	Symbol documentation
										</h3>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	如果是在Xcode项目的源代码中：
											</p>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
											<li style="font-size:15px;">
												包含Markdown的单行注释用///表示：
											</li>
												</ul>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/// A **demo** function</span> <span class="hljs-func"><span class="hljs-keyword" style="color:#EBBBFF;">func</span> <span class="hljs-title" style="color:#99FFFF;">demo</span><span class="hljs-params" style="color:#FFC58F;">()</span></span> {}</pre>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
												<li style="font-size:15px;">
													包含Markdown的多行注释用下面的代码表示：
												</li>
											</ul>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/**
  * item1
  * item2
  * item3
*/</span> <span class="hljs-func"><span class="hljs-keyword" style="color:#EBBBFF;">func</span> <span class="hljs-title" style="color:#99FFFF;">demo1</span><span class="hljs-params" style="color:#FFC58F;">()</span></span> {
}</pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	我们这样添加的注释会显示在哪呢？主要有两个地方，Apple管它们叫做symbol documentation，我们可以用两种方式来查阅它：
										</p>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
										<li style="font-size:15px;">
											把光标放到demo1所在的行上，按住Ctrl点一下，就会弹出这个函数的说明，可以看到Xcode已经把markdown注释渲染了；
										</li>
											</ul>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
											<div class="col-md-12">
												<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-4@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
											</div>
												</div>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
												<li style="font-size:15px;">
													按Option + Command + 2打开Quick Help Inspector，保持光标在demo1()所在行，同样，我们可以看到被渲染过的Markdown注释；
												</li>
													</ul>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
													<div class="col-md-12">
														<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-5@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
													</div>
														</div>
<blockquote style="font-family:" font-size:17.5px;color:#555555;background-color:#ffffff;"="">
														<p style="font-size:15px;">
															简单来说，在Playground里编写markdown注释时，注释起始的第三个字符用:，在项目源代码中编写markdown注释时，注释起始的第三个字母分别用/和*。
														</p>
															</blockquote>
															<hr />
															<h2 id="toc_4" style="font-family:" font-weight:normal;color:#555555;font-size:24px;background-color:#ffffff;"="">
	常用的注释范式
																</h2>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	接下来，我们看来一些在Playground和项目代码中经常会用到的注释范式。至于其中用到的Markdown语法，大家应该都比较熟悉，我们就不一一去解释了。大家也可以在<a href="https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#/apple_ref/doc/uid/TP40016497-CH2-SW1">这里查看Apple官方的Swift markdown语法说明</a>。
																	</p>
																	<hr />
																	<h3 id="toc_5" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	标记重要事项
																		</h3>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	当我们用Playground告知开发者代码中的重要事项时，可以采用下面这种类似的方式进行注释：
																			</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/*:
  &gt; # IMPORTANT: something important you want to mention:
  A general descripiton here.
  1. item1
  1. item2
  1. item3
  ---
  [More info - Access boxueio.com](https://boxueio.com)
 */</span> </pre>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
																			<li style="font-size:15px;">
																				一行简短的重要提示标题；
																			</li>
																			<li style="font-size:15px;">
																				一段内容摘要；
																			</li>
																			<li style="font-size:15px;">
																				一个注意事项列表；
																			</li>
																			<li style="font-size:15px;">
																				一个提供更多内容的链接；
																			</li>
																				</ul>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	在Playground里，上面的注释可以被渲染成这样：
																					</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																					<div class="col-md-12">
																						<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-6@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																					</div>
																						</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	如果我们要把上面的注释放在项目代码里，出了要使用/**开始外，我们还要去掉第一行的&gt;，因为Quick Help不支持这样的Markdown：
																							</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/**
  # IMPORTANT: something important you want to mention:
  A general descripiton here.
  1. Start with
  1. Write anything important you want to emphasize
  1. End with  at a new line.
  ---
  [More info - Access boxueio.com](https://boxueio.com)
 */</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	这样，它看起来，就是这样的：
																						</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																						<div class="col-md-12">
																							<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-7@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																						</div>
																					</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	有关函数自身的注释范式，稍后我们会看到。接下来，我们先看一个简化注释输入的方法。
																				</p>
																				<hr />
																				<h3 id="toc_6" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	在Playground之间跳转
																					</h3>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	有时，为了演示一个项目的不同用法和功能，我们可能会在项目中使用多个Playground文件。为了方便在注释中浏览，我们可以在Playground markdown注释中，添加文件跳转链接。
																						</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	选中项目中的MyPlayground，点击右键，选择“New Playground Page”，添加2个新的page进来，我们把这些页面分别命名成Page1 / Page2 / Page3。
																					</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	在新添加进来的page2和page3里，先分别添加一个标题注释以方便区分它们。然后我们可以看到，在Playground页面的头部和尾部，Xcode已经为我们自动添加了两个链接：
																						</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">//: [Previous](@previous)</span> <span class="hljs-comment" style="color:#7285B7;">//: [Next](@next)</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	按Option + M，切换到渲染模式，分别点击页面上的Previous和Next链接，就会发现可以在页面间前后跳转了。实际上，这里用了两个关键字，@previous和@next，Xcode会自动把它们渲染成跳转到项目文件列表中前、后两个文件的链接。
																					</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	当然，我们也可以实现跨文件跳转，打开Page1，这次在括号里写上要跳转到的目标Playground页面的名字：
																						</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">//: [To Page3](Page3)</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	再切换到渲染模式，点击“To Page3”，就可以跳转到相应的Playground页面了。接下来，我们来看如何通过Xcode Code Snipeet Library简化复杂注释的输入。
																					</p>
																					<hr />
																					<h2 id="toc_7" style="font-family:" font-weight:normal;color:#555555;font-size:24px;background-color:#ffffff;"="">
	Code Snippets Library
																						</h2>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	首先，把之前我们用过的注释块，抽象成一个内容模板：
																							</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/*:
  &gt; # IMPORTANT: &lt;#something important#&gt;
  &lt;#General description#&gt;
  1. &lt;#item1#&gt;
  1. &lt;#item2#&gt;
  1. &lt;#item3#&gt;
  ---
  [More info - &lt;#ref#&gt;](&lt;#Link#&gt;)
*/</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	基本内容和之前还是一样的，只不过，我们把其中需要输入内容的地方用一对&lt;# ... #&gt;包围了起来，这用于告诉Xcode，这些内容是需要每次用户单独输入的。
																						</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	其次，我们选中要添加的代码块，先不要着急拖动，按住等待一会儿，直到鼠标从输入状态变回指针状态；
																							</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	第三、把代码块拖动到Code Snippets Library：
																						</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																						<div class="col-md-12">
																							<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-8@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																						</div>
																							</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	这样，在Code Snippets Library里，就会多出来一项，表示我们新添加的代码片段，在图标的左下角，左右一个“User”字样，表示这是我们自定义的代码片段：
																								</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																								<div class="col-md-12">
																									<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-9@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																								</div>
																									</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	第四、点击“Edit”按钮，编辑一下这个代码片段：
																										</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																										<div class="col-md-12">
																											<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-10@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																										</div>
																											</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	其中：
																												</p>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
																												<li style="font-size:15px;">
																													Title表示代码片段的名称；
																												</li>
																												<li style="font-size:15px;">
																													Summary表示代码片段的简单说明；
																												</li>
																												<li style="font-size:15px;">
																													Platform表示代码片段在 iOS / macOS / watchOS / tvOS / All 中使用；
																												</li>
																												<li style="font-size:15px;">
																													Language表示代码片段生效的语言；
																												</li>
																												<li style="font-size:15px;">
																													Completion Shorcut表示如何调出这个代码片段，在这里我们选择输入importantnote，当然你可以设置成任何方便使用的内容；
																												</li>
																												<li style="font-size:15px;">
																													Completion Scopes表示上面设置的Completion Shortcut生效范围，All表示在任意位置都生效；
																												</li>
																													</ul>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	设置完成后，点击"Done"。这样当我们在Swift代码里输入importantnote的时候，就能调出需要的注释片段，我们只要直接设置其中的内容就好了。
																														</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	接下来，我们将看到一些常用的注释范式，它不仅可以让代码易于维护和交流，就像API设计指南中的描述的那样，可以有效的激发我们的设计灵感。
																													</p>
																													<hr />
																													<h3 id="toc_8" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	标记自定义类型的常用范式
																														</h3>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	对于一个自定义类型来说，我们要在注释中说明以下问题：
																															</p>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
																															<li style="font-size:15px;">
																																一句话描述；
																															</li>
																															<li style="font-size:15px;">
																																类型主要功能；
																															</li>
																															<li style="font-size:15px;">
																																常用的初始化方法以及拷贝语义；
																															</li>
																															<li style="font-size:15px;">
																																补充说明；
																															</li>
																																</ul>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	而对这些问题的阐述，正是我们设计这个类型的过程。因此，在编码前设计注释文档，可以很好的帮我们整理设计思路。
																																	</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	例如，我们创建一个包含整数的struct IntArray，在Playground里添加下面的注释：
																																</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/*:
 `IntArray` is a C-like random access collection of integers.
 
 ## Overview
 An `IntArray` stores values of integers in an ordered list.
 The same value can appear in an IntArray multiple times at
 different positions.

 ## Initializers
 You can create an IntArray in the following ways:
 
    // An empty IntArray
    var empty: IntArray = []

    // Initialzied by an array literal
    var odds: IntArray = [0, 2, 4, 6, 8]
 
    // Initialized by a default value
    var tenInts: IntArray = IntArray(repeating: 0, count: 10)

 ## Value semantics
 - important:
 `IntArray` object perform value type semantics. But we have the COW optimization.
 
 Like all value types, `IntArray` use a COW optimization.
 Multiple copies of `IntArray` share the same storage as long as
 none of the copies are modified.
 
 ---
 
 - note:
 Check [Swift Standard Library](https://developer.apple.com/reference/swift/array) 
 for more informaton about arrays.
 */</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	上面的注释被Xcode渲染出来是这样的：
																																	</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																																	<div class="col-md-12">
																																		<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-11@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																																	</div>
																																		</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	而把这段注释移植到Xcode项目代码中，在Quick Help中看到的结果是这样的：
																																			</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																																			<div class="col-md-12">
																																				<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-12@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																																			</div>
																																				</div>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	当然，你可以任意在注释里添加希望其它开发者了解的内容，例如访问、存取、修改数组的方法等。也可以通过Snippet library，把它保存起来。
																																					</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	在上面的注释里，有几个用法是要特别说明下的：
																																				</p>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
																																				<li style="font-size:15px;">
																																					我们可以在注释中使用`single line of code`来插入单行代码；
																																				</li>
																																				<li style="font-size:15px;">
																																					在注释中插入代码块时，<span style="font-weight:700;">代码块的缩进要和当前最近的一个内容缩进有4个以上的空格</span>，否则XCode不会识别；
																																				</li>
																																				<li style="font-size:15px;">
																																					我们在注释中使用了两个用-开始的标记，它们叫做callout，实际上你可以选择使用加号、减号或乘号来表示一个callout。XCode可以识别它们，并突出显示其中的内容。大家可以在<a href="https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/MarkupFunctionality.html#/apple_ref/doc/uid/TP40016497-CH54-SW1">这里</a>找到所有的callout元素列表。要说明的是，并不是所有callout都可以同时在Playground和Quick Help中使用，选择的时候，要注意这点；
																																				</li>
																																				<li style="font-size:15px;">
																																					最后，我们可以<span style="font-weight:700;">使用三个及以上的</span>-，表示一条分割线，用来区分正文和内容引用的部分；
																																				</li>
																																					</ul>
																																					<hr />
																																					<h3 id="toc_9" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	标记函数或方法的常用范式
																																						</h3>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	通常，对一个方法的描述，更多是用在Quick Help里。对于一个函数来说，最重要的内容无非有以下：
																																							</p>
<ul style="font-family:" color:#555555;font-size:13px;background-color:#ffffff;"="">
																																							<li style="font-size:15px;">
																																								一句话功能描述；
																																							</li>
																																							<li style="font-size:15px;">
																																								常见应用场景；
																																							</li>
																																							<li style="font-size:15px;">
																																								参数；
																																							</li>
																																							<li style="font-size:15px;">
																																								返回值；
																																							</li>
																																							<li style="font-size:15px;">
																																								时间复杂度；
																																							</li>
																																								</ul>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	如果我们要在上面IntArray里，添加一个“返回不包括末尾N个元素的IntArray”的方法：
																																									</p>
<pre class="hljs">public <span class="hljs-func"><span class="hljs-keyword" style="color:#EBBBFF;">func</span> <span class="hljs-title" style="color:#99FFFF;">dropLast</span><span class="hljs-params" style="color:#FFC58F;">(<span class="hljs-number">_</span> n: Int)</span></span> -&gt; <span class="hljs-type">IntArray</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	它的注释可以是这样的：
																																								</p>
<pre class="hljs"><span class="hljs-comment" style="color:#7285B7;">/// Returns a subsequence containing all but the specified number of final</span> <span class="hljs-comment" style="color:#7285B7;">/// elements.</span> <span class="hljs-comment" style="color:#7285B7;">///</span> <span class="hljs-comment" style="color:#7285B7;">/// If the number of elements to drop exceeds the number of elements in the</span> <span class="hljs-comment" style="color:#7285B7;">/// collection, the result is an empty subsequence.</span> <span class="hljs-comment" style="color:#7285B7;">///</span> <span class="hljs-comment" style="color:#7285B7;">///     let numbers = [1, 2, 3, 4, 5]</span> <span class="hljs-comment" style="color:#7285B7;">///     print(numbers.dropLast(2))</span> <span class="hljs-comment" style="color:#7285B7;">///     // Prints "[1, 2, 3]"</span> <span class="hljs-comment" style="color:#7285B7;">///     print(numbers.dropLast(10))</span> <span class="hljs-comment" style="color:#7285B7;">///     // Prints "[]"</span> <span class="hljs-comment" style="color:#7285B7;">///</span> <span class="hljs-comment" style="color:#7285B7;">/// - Parameter n: The number of elements to drop off the end of the collection.</span> <span class="hljs-comment" style="color:#7285B7;">///   `n` must be greater than or equal to zero.</span> <span class="hljs-comment" style="color:#7285B7;">///</span> <span class="hljs-comment" style="color:#7285B7;">/// - Returns: A subsequence that leaves off `n` elements from the end.</span> <span class="hljs-comment" style="color:#7285B7;">///</span> <span class="hljs-comment" style="color:#7285B7;">/// - Complexity: O(*n*), where *n* is the number of elements to drop.</span> </pre>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	通常，多行的代码注释也可以使用这种多个单行注释拼接的形式来编写，因为有时多行缩进的不同，会让整个注释从头部看起来比较混乱（大家可以对比下前面我们对IntArray的注释），而使用多个///则看起来会整齐一些。
																																									</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	在这个例子里，我们使用了三个callout，分别表示了方法的参数、返回值和时间复杂度，<span style="font-weight:700;">如果算法复杂度是O(1)，那默认是可以省略的</span>。
																																								</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	在Quick Help里，它看上去是这样的：
																																									</p>
<div class="row" style="font-family:" margin-left:-15px;color:#555555;font-size:13px;background-color:#ffffff;"="">
																																									<div class="col-md-12">
																																										<img src="https://o8lw4gkx9.qnssl.com/br-markdown-comment-13@2x.jpg" alt="Rendered markdown" style="width:750px;" /> 
																																									</div>
																																										</div>
																																										<hr />
																																										<h3 id="toc_10" style="font-family:" font-weight:normal;color:#555555;font-size:20px;background-color:#ffffff;"="">
	标记属性的常用范式
																																											</h3>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	关于属性的注释，我们只强调一点，就是对于computed property来说，<span style="font-weight:700;">如果它的算法复杂度不是O(1)，必须在注释中予以说明</span>。因为对于绝大多数人来说，不会预期访问一个属性会带来严重的性能开销。
																																												</p>
<p style="font-family:" color:#555555;font-size:15px;background-color:#ffffff;"="">
	以上，就是在Swift 3 API设计指南中，关于注释的内容。<span style="font-weight:700;">在编码前，用写文档的方式来编写注释</span>，可能在初期会让我们觉得不适应，或者觉得没必要，但至少在设计一个新的类型或方法时，尝试着去做它们，它会让你明确类型表达的语意，理清方法功能的边界，进而让你的代码，更加易于理解和交流。
																																											</p> </p>
			     </div>

 		</div>
	</div>
  </div>
  
  
	<div class="site-footer container clearfix">   
	     <ul class="site-footer-links">
	       
	         <li><a href="http://www.swiftv.cn/news/page/lianxi"  >友情链接：</a></li>
	         <li><a href="http://www.swiftv.net"  target="_blank"  >Swift的那点事</a></li>
	         <li><a href="http://Letsswift.com/"  target="_blank"  >一起Swift</a></li>
	         <li><a href="http://www.ucai.cn/index.php?app=home&mod=Public&act=blogroll"  target="_blank"  >优才网</a></li>
	         <li><a href="http://www.9ria.com/"  target="_blank"  >9Ria游戏开发者社区</a></li>
	         <li><a href="http://www.swiftvip.cn"  >Swift中文网</a></li>
	         <li><a href="http://www.swift51.com/"  target="_blank"  >雨燕社区</a></li>
	         <li><a href="http://www.rupeng.com/friendsLink.shtml"  target="_blank"  >如鹏网(.NET/JAVA)</a></li>
	         <li><a href="http://www.ruanman.net"  target="_blank"  >软曼网</a></li>
	         <li><a href="https://mos.meituan.com/doc/about"  target="_blank"  >美团云</a></li>
	         <li><a href="http://www.maiziedu.com/"  target="_blank"  >麦子学院</a></li>
	         <li><a href="http://www.superqq.com/"  target="_blank"  >刚刚在线</a></li>
	         <li><a href="http://wgh.me/"  target="_blank"  >Sally</a></li>
	         <li><a href="http://www.oneapm.com/"  target="_blank"  >应用性能管理</a></li>
	         <li><a href="http://www.51ios.net/"  target="_blank"  >51iOS</a></li>
	         <li><a href="https://boxueio.com/"  target="_blank"  >泊学-全栈自学之路</a></li>
	         <li><a href="http://www.xsteach.com/"  target="_blank"  >邢帅教育</a></li>
	         <li><a href="http://www.i3done.com/"  target="_blank"  >3Done</a></li>
	         <li><a href="http://www.wyzc.com/"  target="_blank"  >我赢职场</a></li>
	         <li><a href="../page/qun.html"  >QQ群公布</a></li>
	         <li><a href="../page/yijian.html"  target="_blank"  >用户体验持续改进计划</a></li>
	     </ul>
	  
	  <div class="alert text-center"><a href="http://www.miitbeian.gov.cn/" target="_blank"> 粤ICP备14044760-1</a></div>
	</div>
	
	<div><script>window._bd_share_config={"common":{"bdSnsKey":{"tsina":"3474175605"},"bdText":"SwiftV课堂，是我见过的最有氛围的Swift视频学习站，体验很棒！小伙伴要不要一起来学习？限免哟~#SwiftV课堂#","bdMini":"1","bdMiniList":false,"bdPic":"","bdStyle":"0","bdSize":"16"},"slide":{"type":"slide","bdImg":"3","bdPos":"left","bdTop":"214.5"}};with(document)0[(getElementsByTagName('head')[0]||body).appendChild(createElement('script')).src='http://bdimg.share.baidu.com/static/api/js/share.js?v=89860593.js?cdnversion='+~(-new Date()/36e5)];</script></div>



  
<div id="ScrollToTop" class="btnimg Button2" style="color: rgb(255, 255, 255);text-align: center; display: block; background-color: rgba(12, 173, 87, 0.69);padding: 11px; width: 60px;bottom:15px;">返回<br>顶部</div>
  <div id="login-modal" class="modal" data-url="/login/ajax"></div>
  <div id="modal" class="modal"></div>


<script src="http://static.vlms.cn/resources/js/jquery.form.min.js"></script>
<script src="http://static.vlms.cn/resources/js/bootstrapValidator.min.js"></script>
<script src="http://static.vlms.cn/resources/bootstrap/js/bootstrap.min.js"></script>
<script src="http://static.vlms.cn/resources/js/autocomplete.js"></script>
<script src="http://static.vlms.cn/resources/js/bootstrap-notify.js"></script>





  
  <!-- 统计代码 -->
  <script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "//hm.baidu.com/hm.js?1e733c39d359b2149cd361e97999460b";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-52703035-1', 'auto');
  ga('send', 'pageview');
</script>


  </body>
</html>